Skip to content

feat(ios): serve Vite dev over the USB CoreDevice tunnel - #6210

Draft
edusperoni wants to merge 1 commit into
feat/vite-single-processfrom
feat/vite-usb-tunnel
Draft

edusperoni wants to merge 1 commit into
feat/vite-single-processfrom
feat/vite-usb-tunnel

Conversation

@edusperoni

Copy link
Copy Markdown
Collaborator

PR Checklist

Stacked on #6209 (feat/vite-single-process); review that one first. Pairs with NativeScript/NativeScript#11650 (the @nativescript/vite side, as of 79c30e03c: the dev server listens on :: and an IPv6 NS_HMR_HOST is bracketed in URLs).

Important

HMR over the tunnel needs the websockets fix from valor-software/nativescript-plugins#27, which is not released yet. With @valor/nativescript-websockets 2.0.3 the app loads all of its modules over the tunnel, but the Vite HMR socket never connects: the iOS handshake sends the IPv6 host unbracketed, and Vite rejects the upgrade. Until #27 ships, a session with one USB iPhone gets no hot updates by default. The only way out today is setting NS_HMR_HOST by hand (for example to the LAN address).

What is the current behavior?

  • A physical iPhone or iPad loads a Vite HMR app from the Mac's LAN address, the same one the simulator uses. That needs both on the same Wi-Fi network, and the app has to get past the iOS Local Network prompt.
  • iOS 17+ devices on USB have a CoreDevice tunnel to the Mac (a utun with an fdXX::/64 ULA pair) that an app can reach without Wi-Fi and without the prompt. Nothing uses it.

What is the new behavior?

The CLI opens the device's CoreDevice tunnel itself and keeps it open for the session. Nothing keeps one open otherwise: the CLI's own device channel (ios-device-lib) never opens one, a tunnel closes about 5-10 s after its last client goes away, and every new tunnel gets a new address.

  • When: a Vite HMR watch session (not release) where the platform's only target is a physical iOS 17+ / visionOS device on USB (devicectl reports transportType: wired), and the installed @nativescript/vite lists the platform under nativescriptCli.singleProcessDev. Older releases bind the dev server to NS_HMR_HOST and put an IPv6 literal into URLs without brackets, so they keep today's behavior.
  • How: before prepare, the run controller spawns xcrun devicectl device notification observe --device <udid> … with a one-year session timeout to hold the tunnel. It then polls devicectl list devices --json-output (up to 10 s) until the device's tunnelState is connected. tunnelIPAddress there is the device's end (fdXX::1). The Mac's end is the local interface address in the same subnet (fdXX::2 on the utun), read from os.networkInterfaces().
  • That address goes to both Vite children as NS_HMR_HOST for that platform only, so bundle.mjs boots from http://[fdXX::2]:<port>. Other platforms in the same CLI process are unaffected.
  • The holder is killed when the device leaves the session or the CLI exits. If it dies on its own (cable pulled), the CLI warns once that the app lost the dev server and that the run has to be restarted. ns run does not add a replugged device back to a running session, so the new tunnel address never has to be applied to a running dev server.
  • Unchanged: a user-set NS_HMR_HOST always wins, and no tunnel is opened then. Simulators, Wi-Fi or network-paired devices, iOS < 17, non-macOS hosts, a missing devicectl and tunnels that do not come up all keep the LAN host from @nativescript/vite, with one trace line. A session with more than one device of the platform also stays on LAN: one dev server bakes one origin into bundle.mjs, and a tunnel address is reachable only from its own device (and not from the Mac itself, so not from a simulator either). Android is untouched.

Verification

  • iPhone (iOS 26, USB), Vue fixture, single-process session:
    • The CLI logged Using the USB tunnel to … (Mac address fdXX::2).
    • bundle.mjs contains only http://[fdXX::2]:5173.
    • Every dev server request (78 on a cold launch) came from the device's tunnel address fdXX::1, none from the LAN.
    • An edit to a .vue file produced hmr update, and the device fetched the updated module over the tunnel. This was with the websockets platform update command #27 build swapped in, see above.
    • The address stayed the same for the 5 minutes of the session.
    • Ctrl-C left no devicectl holder behind.
  • Tunnel behavior, measured with devicectl: the address is stable while any holder lives, and two overlapping holders share one tunnel. It closes 5-10 s after the last holder exits. A new holder gets a new /64.
  • Not run on a device: the two-process (vite build --watch + vite serve) path, which is unit-tested only, a locked device and Mac sleep.
  • CLI unit suite: 2204 tests passing (9 skipped). New specs cover the tunnel service (eligibility, devicectl parsing, the Mac-side address, holder lifecycle), the run controller's single-target rule and close-on-stop, the NS_HMR_HOST hand-off and the package capability check.

Stacked on #6209. Pairs with NativeScript/NativeScript#11650.

A USB-connected iOS 17+ / visionOS device reaches the Mac over a
CoreDevice tunnel (a utun with an fdXX::/64 ULA pair) without Wi-Fi and
without the Local Network prompt. The tunnel only exists while a client
holds it, and every new tunnel gets a new address.

For a Vite HMR session whose only target of a platform is such a
device, the run controller now opens the tunnel before prepare: it
holds it with `devicectl device notification observe` for the session,
reads the device's end from `devicectl list devices`, and takes the
Mac's address in the same subnet from the local interfaces. The bundler
passes that address to both Vite children as NS_HMR_HOST, so bundle.mjs
and the dev server use the tunnel origin. The holder is killed when the
device leaves the session or the CLI exits; if it dies on its own the
CLI warns that the app lost the dev server.

Only an @nativescript/vite that lists the platform under
nativescriptCli.singleProcessDev gets the tunnel: older releases bind
the dev server to NS_HMR_HOST and put an IPv6 literal into URLs
unbracketed. A user-set NS_HMR_HOST, simulators, Wi-Fi or
network-paired devices, iOS < 17, a missing devicectl, a tunnel that
does not come up and sessions with more than one device of the platform
also keep the LAN host from @nativescript/vite, with one trace line.
@coderabbitai

coderabbitai Bot commented Nov 21, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant